package com.kexio.file.service;

import java.util.List;

import com.baomidou.mybatisplus.extension.service.IService;
import com.kexio.file.entity.FileVersion;
import com.kexio.file.vo.FileVersionVO;

/**
 * 文件版本管理服务接口
 * 
 * @author Kexio Team
 * @since 1.0.0
 */
public interface FileVersionService extends IService<FileVersion> {

    /**
     * 创建新版本
     *
     * @param fileId 文件ID
     * @param storageObjectId 存储对象ID
     * @param changeLog 版本变更说明
     * @param versionTags 版本标签
     * @param setAsCurrent 是否设为当前版本
     * @return 新版本信息
     */
    FileVersion createNewVersion(String fileId, String storageObjectId, String changeLog, 
                                 String versionTags, Boolean setAsCurrent);

    /**
     * 获取文件的所有版本
     *
     * @param fileId 文件ID
     * @return 版本列表
     */
    List<FileVersionVO> getVersionsByFileId(String fileId);

    /**
     * 获取文件的当前版本
     *
     * @param fileId 文件ID
     * @return 当前版本
     */
    FileVersionVO getCurrentVersion(String fileId);

    /**
     * 根据版本号获取版本信息
     *
     * @param fileId 文件ID
     * @param versionNumber 版本号
     * @return 版本信息
     */
    FileVersionVO getVersionByNumber(String fileId, Integer versionNumber);

    /**
     * 切换到指定版本
     *
     * @param fileId 文件ID
     * @param versionId 版本ID
     * @return 是否成功
     */
    boolean switchToVersion(String fileId, String versionId);

    /**
     * 回滚到指定版本
     *
     * @param fileId 文件ID
     * @param versionNumber 版本号
     * @param changeLog 回滚说明
     * @return 新创建的版本信息
     */
    FileVersion rollbackToVersion(String fileId, Integer versionNumber, String changeLog);

    /**
     * 删除指定版本
     *
     * @param versionId 版本ID
     * @param force 是否强制删除（如果是当前版本）
     * @return 是否成功
     */
    boolean deleteVersion(String versionId, Boolean force);

    /**
     * 删除文件的所有版本
     *
     * @param fileId 文件ID
     * @return 是否成功
     */
    boolean deleteAllVersions(String fileId);

    /**
     * 获取版本对比信息
     *
     * @param fileId 文件ID
     * @param fromVersion 源版本号
     * @param toVersion 目标版本号
     * @return 对比信息
     */
    String compareVersions(String fileId, Integer fromVersion, Integer toVersion);

    /**
     * 统计文件版本数量
     *
     * @param fileId 文件ID
     * @return 版本数量
     */
    int countVersions(String fileId);

    /**
     * 批量查询文件的版本数量
     *
     * @param fileIds 文件ID列表
     * @return 文件ID与版本数量的映射
     */
    java.util.Map<String, Integer> batchCountVersions(List<String> fileIds);

    /**
     * 清理指定文件的历史版本（保留最近N个版本）
     *
     * @param fileId 文件ID
     * @param keepCount 保留版本数量
     * @return 清理的版本数量
     */
    int cleanupHistoryVersions(String fileId, Integer keepCount);

    /**
     * 获取版本状态文本
     *
     * @param status 状态值
     * @return 状态文本
     */
    String getVersionStatusText(Integer status);

    /**
     * 转换为VO对象
     *
     * @param fileVersion 文件版本实体
     * @return VO对象
     */
    FileVersionVO convertToVO(FileVersion fileVersion);

    /**
     * 批量转换为VO对象
     *
     * @param fileVersions 文件版本实体列表
     * @return VO对象列表
     */
    List<FileVersionVO> convertToVOList(List<FileVersion> fileVersions);
}
